<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html style="direction: ltr;" lang="en">
<head>





  <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">





  <meta name="Generator" content="Internet Assistant for Word Version 3.0">




  <title>First steps</title>
</head>


<body>




<h1 style="text-align: center;">COID  - First Steps</h1>


<center>LINUX</center>


<br>



<br>


<h3>Installation</h3>




<ul>


  <li>get the latest Linux (!) version of coid from&nbsp;<a href="http://coid.sourceforge.net/">http://coid.sourceforge.net/</a></li>


</ul>



<ul>


  <li>
untar it to a fitting directory, e.g. /usr/local (but not /usr/local/bin, because the executable coid is placed there) <br>


  </li>


</ul>


<ul>


  <li>

go to the directory you have chosen and run&nbsp;<code>make</code></li>


</ul>


&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;You probably have to install the library
'curses' first. With SuSE just install the standard curses-devel
package using YAST. Afterwards you have to make a static link on
libncurses<br>



&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<code>ln -s libncurses.a /usr/lib/libcurses.a</code><br>



<ul>


  <li>run 'make install'<big><font face="Times New Roman, Times, serif"><font face="Thorndale AMT"><br>


    </font></font></big></li>


</ul>



<br>


<h3 style="font-family: Times New Roman,Times,serif;">Directory structure</h3>




The following directories are created:<br>



<code>/usr/local/bin&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code>contains the executables coid, coidgen, coidc<br>



<code> /usr/local/lib/coid&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code>contains libcoidserver.so<br>



<code> /usr/local/lib/coid/device&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code>contains the .dev files <br>



<code>/etc/coid/&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code>contains assert.log

<br>

<br>


<h3 style="font-family: Times New Roman,Times,serif;">Creating the server-side files</h3>



&nbsp;&nbsp;&nbsp; Let's assume you already have a header
file (example.h), containing the class you want to export (to export
means to make it available as a service on a coid server). It's
important that this file contains only one decorated (= meant to be
exported) class. More about the decoration of the header file with
keywords in the <a href="example_program.html">example</a> document.<br>


It's recommended that you place your header file in <code>/coid_directory/apps/projectname/.</code> <br>


<br>


At first you have to run coidgen. In case you want to compile your
server and client on different machines, just run coidgen once (on one
machine!) and distribute the generated files afterwards.

<br>




&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<code>coidgen example.h</code><br>


<br>


This generates the whole communication layer for the client and server
from information found in that header, without modifying the class. <br>


The output of coidgen is a set of files for the client (the directory
'client' is created for it) and for the server (is placed in the same
directory as the service header). In our example it would generate
example_dispatch.h, Makefile, client/example_client.cpp and
client/example_client.h.<br>


<br>



 The server source file is postfixed with <span style="font-style: italic;">_dispatch</span>.
To generate a file (device) that the server can load (.dev), you have
to run make. The makefile therefore was also generated by&nbsp;coidgen
before.<br>


<br>


make will generate the .dev file. It's named <code>[ExportedClass].dev</code> and is being placed in <code>/coid_directory/bin/device/[ExportedClass]/</code>.
 <br>



That's nearly everything you have to do on the server side. Just copy the [ExportedClass] directory to <code>/usr/local/lib/coid/device</code>. The server looks by default only in this directory for the devices. <br>


<br>



The command therefore could look like:<br>


<code>&nbsp;&nbsp;&nbsp; cp -r /usr/local/coid/bin/device/TestClass/ /usr/local/lib/coid/device<br>


<br>


</code>
Attention: Do not overwrite a currently used device! (Shut down server first)
<br>


<br>



Once the coid server has been started and has loaded the device file,
the exported class can be called remotely from clients. Communication
takes place over network or in case the server and client are on the
same machine, coid uses interprocess communication.<br>



For more information about coidgen read&nbsp;<a href="http://coid.sourceforge.net/web/coidgen.html">http://coid.sourceforge.net/web/coidgen.html</a>. <br>



<br>


<h3>Creating the client-side files</h3>




As written above coidgen creates the client directory and puts a
[service header file]_client.cpp and a [service header file]_client.h
file in there, e.g. example_client.cpp and example_client.h. <br>


<br>


The header file (_client.h) contains the declaration of the exported
class. The source file (_client.cpp) implements the methods as calls to
the coid server over the network. <br>


In case of the client there is no Makefile generated by&nbsp;coidgen.
That's because the client files normally become a part of an existing
project. <br>


<br>


Let's say there is a client.cpp, which is calling a few methods from
the exported class. In this case you would have to compile the client
like that:<br>




<br>


<code>g++ -Wall -I/usr/local example_client.cpp client.cpp /usr/local/coid/comm/comm.a -lpthread -ldl -o client<br>


<br>


</code>

So you have to compile these two files:<br>



&nbsp;&nbsp;&nbsp; <code>example_client.cpp &nbsp;&nbsp;&nbsp; &nbsp;</code>the generated _client.cpp file<br>



&nbsp;&nbsp;&nbsp; <code>client.cpp &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;</code>your client file(s) - a detailed example follows<br>




and include three libraries:<br>



&nbsp;&nbsp;&nbsp; <code>/usr/local/coid/comm/comm.a&nbsp;&nbsp; &nbsp;</code>the&nbsp;comm.a library<br>



&nbsp;&nbsp;&nbsp; <code>-lpthread&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;</code>the libpthread library<br>



&nbsp;&nbsp;&nbsp; <code>-ldl&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;</code>the libdl library<br>


<br>



This generates the executable client. You can run it just like any
other program, but&nbsp;the coid server has to run (not necessarily
local).<br>



<br>


<h3>The COID server</h3>




To start the coid server you just have to type coid. In this case the
server uses by default the port 55099, looks for the device files in <code>/usr/local/lib/coid/devic</code>e and&nbsp;starts all services found in this files. <br>



If you want to change these defaults, you will have to create a .devconf configuration file.<br>



To start the server using a .devconf file, type <code>coid /devconf_directory/</code>. <br>




<br>


The .devconf file can contain these lines:<br>



<code>
'port' PORT<br>



'directory' NAME<br>



'default' ('all' | 'none')<br>



'service' NAME ('port' NUM)? ('dir' PATH)?<br>



'!service' NAME<br>


</code>
<br>



<code>port&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;</code>That's the server port the client has to connect to.<br>



<code>directory&nbsp;&nbsp;</code>&nbsp;&nbsp;In this directory (and subdirectories) the server looks for .dev files.<br>



<code>default&nbsp;&nbsp; &nbsp;&nbsp;</code>all (load all services) / none (just load services listed with service)<br>



<code>!service&nbsp;&nbsp; &nbsp;</code>do not load service NAME<br>



<code>service&nbsp;&nbsp; &nbsp;&nbsp;</code>load service NAME,
optionally using an additional acceptor port (not coid acceptor port!)
and working directory (not device directory!)<br>



<br>


Once started, you will see a listing which services have been started.
If your service (the name is your exported class) is listed, everything
went well and you can start your client.<big><font face="Times New Roman, Times, serif"><font face="Thorndale AMT" lang="JA"><br>



</font></font></big><br>



<h3>Automation of the compiling process</h3>




Since there are a lot of steps to do to get from the service header
file to the device file and from the client source to the executable,
it's handy to have a script doing that. It could look like that for
example:<big><font face="Times New Roman, Times, serif"><font face="Thorndale AMT" lang="JA"><br>



<code>
<br>

</code></font></font></big><code>
#!/bin/bash <br>



echo "***************************"<br>



echo "****** coid shutdown ******"<br>



echo "***************************"<br>



killall coid<br>




echo "*********************"<br>



echo "****** coidgen ******"<br>



echo "*********************"<br>



cd /usr/local/coid/apps/example/<br>



coidgen ./example.h<br>




echo "***************************"<br>



echo "****** make (server) ******"<br>



echo "***************************"<br>



make<br>




echo "********************"<br>



echo "****** client ******"<br>



echo "********************"<br>




cd /usr/local/coid/apps/example/client<br>



g++ -Wall -I/usr/local example_client.cpp client.cpp /usr/local/coid/comm/comm.a -lpthread -ldl -o client<br>




echo "***********************"<br>



echo "****** copy .dev ******"<br>



echo "***********************"<br>



cp -r /usr/local/coid/bin/device/TestClass/ /usr/local/lib/coid/device<br>




echo ""<br>



echo "--&gt; todo: coid restart"</code><big><font face="Times New Roman, Times, serif"><font face="Thorndale AMT" lang="JA"><code><br>


<br>


</code></font></font></big>

The directories and filenames have to be modified appropriately.<br>




<br>



<h3>More services in one device</h3>


It is possible to link more than one service in a single device.
Therefore just run coidgen for every service header file and then run
make. make links all _dispatch.h files to the device. <br>



On the client side just include all _client files.<big><font face="Times New Roman, Times, serif"><font face="Thorndale AMT" lang="JA"><br>




</font></font></big>
</body>
</html>
